Repository navigation
Keep write scopes on demand during Todo preparation - #9078
loopx-agent wants to merge 4 commits into
Conversation
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
…selection-scope-read-20261119 Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: actor_kind=model_agent, declared_model=Gemini, declared_provider=Google, declaration_source=self_reported
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
本次针对 PR #9078(Keep write scopes on demand before Todo selection,head 5b28c0594028ec213fcca4a4a09e83b36e15d3fd,基于 origin/main ff905437669054465a4d7aa8c70ba3396aaf9182)的独立 exact-head 审查结论为:APPROVE(无阻塞缺陷)。
动机 / Motivation
当调度宿主或 Agent 在启用原生渐进上下文交付(--context-delivery on)下执行 quota should-run 或对已保存决策执行 quota context-project,且存在多个可执行候选 Todo 尚未绑定 --todo-id 时,无论是共享检出目录中的工作树修复路径还是独立 worktree 中的普通选单路径都会遭遇首读体积膨胀。
在改动前的基线(ff90543766)上,当首选候选包含较长的允许写入路径列表 required_write_scopes(如 355 条路径、约 21 KB)时,该列表不仅出现在推荐项 selected_todo 中,还重复出现在 action_portfolio.suggested_actions 中:独立 worktree 选单下两处长列表都未折叠,工作树修复选单下候选列表里的同份长范围仍留在首读正文,导致备选候选、选择命令和 context_details 被挤到后续分页,浪费首屏预算。本 PR 实现的可观测改善是:首读保留候选标识、短范围(小于 1024 字节)、选择命令与当前迁移/准备义务,将大于等于 1024 字节的 selected_todo.required_write_scopes 与 action_portfolio.suggested_actions[*].required_write_scopes 留在带摘要校验的原捕获中由 --select 按需读取,并在绑定 --todo-id(及必要时迁出工作树)后通过同一 Turn 的下一次 quota should-run 交付完整当前范围。非目标边界:本 PR 不改变候选排序与准入规则,不改变 --context-delivery off 完整输出,不免除后续选定 Todo 时的真实 guard 再准入,也未测量真实模型端 token 消耗。
改动思路 / Approach
本 PR 复用既有渐进上下文架构中的唯一决策边界:TypeScript 控制面 loopx/control_plane/quota/turn_envelope.ts 内的 progressivePreparationScopes() 向 progressive_context.ts 的 progressiveContextPlan() 与 requiredNativeContext() 传递 PreparationScopeDetail[] 延后清单,Python 侧(quota_capture.py / quota_context_reader.py)仅作为无状态 IO 适配器执行字节切片、SHA-256 校验与 --select 按需恢复。没有引入第二套决策逻辑、新配置开关或新持久化状态。
下表对比了改动前后在关键场景下的首读范围处理路径(基于 ff90543766 与 5b28c05940 的同输入对比):
| 场景 / 路径 | 基线 origin/main (ff90543766) |
本 PR Head (5b28c05940) |
权威状态与约束 |
|---|---|---|---|
agent_workspace_repair + selecting |
仅延后 goal_boundary.write_scope 与 selected_todo.required_write_scopes;suggested_actions[*].required_write_scopes 仍内联 |
同步延后 suggested_actions[*].required_write_scopes(>=1024B),尾注统一追加迁出后重跑 guard 提示 |
delivery_allowed=false、spend_allowed_now=false 不变;重跑 guard 后恢复完整范围 |
normal_run + selecting |
仅延后 goal_boundary.write_scope;selected_todo 与 suggested_actions 长范围均内联 |
同时延后 selected_todo.required_write_scopes 与 suggested_actions[*].required_write_scopes(>=1024B),尾注统一追加就绪后使用完整范围提示 |
selection_required=true、spend_allowed_now=false 不变 |
claim_required (!selecting) |
仅延后 goal_boundary.write_scope |
与基线完全一致 | 不触及已选 Todo 的认领前语义 |
ready (delivery_allowed=true) |
不延后(直接返回空数组) | 与基线完全一致 | 交付前完整写入范围始终内联 |
--context-delivery off / 异常或短列表 |
全部原始字段内联保留 | 与基线完全一致(fail-closed 原样保留) | 默认关闭隔离完整 |
从架构评估来看:展示规划职责留在 TS turn_envelope.ts 的 progressivePreparationScopes 中,使选单与工作树修复的长写入范围折叠与准入/权威边界(run_decision / interaction_contract)及 Python 文件 IO 保持清晰分离,且受 requiredNativeContext 字节缩减与类型校验的 fail-closed 保护。当前 PR 边界仅覆盖未绑定选单与工作树修复场景,保留 claim_required 下 selected_todo.required_write_scopes 既有行为不变,改动内聚且可独立回滚。
具体改动 / Changes
全部改动共 3 个文件(+101 / -6),职责清晰分离:
- 生产运行控制面(
+17 / -6):loopx/control_plane/quota/turn_envelope.ts扩展progressivePreparationScopes()。 - 公开参考文档(
+4 / -0):docs/reference/required-work-context.md补充未绑定选单时候选长写入范围按需读取说明。 - 端到端控制面测试(
+80 / -0):tests/control_plane/test_context_first_read.py新增双模式参数化用例test_unbound_candidate_scopes_are_only_expanded_on_request。
关键代码讲解
-
progressivePreparationScopes(loopx/control_plane/quota/turn_envelope.ts#L2456-L2510)- 职责与输入:在已验证
interaction_contract版本为loopx_interaction_contract_v0、should_run === true、agent_channel.delivery_allowed === false且spend_allowed_now === false && spend_after_validation === false后,识别repair(agent_workspace_repair+agent_workspace_guard)与selecting(hasUnboundActionSelection(cli))和claiming三类准备态。 - 前后变化:原先仅在
repair时把selected_todo.required_write_scopes加入延后清单,且完全忽略action_portfolio.suggested_actions;现改为在repair || selecting时均对合法quota_selected_todo_v0的长required_write_scopes加入延后路径["selected_todo", "required_write_scopes"],并在selecting时遍历action_portfolio.suggested_actions,对每个typeof candidate?.todo_id === "string"且longScope(candidate.required_write_scopes)(字符串数组且 UTF-8 JSON 字节数>= 1024)的候选追加["action_portfolio", "suggested_actions", index, "required_write_scopes"]。最后统一在finalScope(scopes.at(-1))尾部拼接当前阶段义务提示(repair强调迁出后同 Turn 重跑 guard;非repair强调交付前使用就绪决策中的完整当前范围),避免每条范围重复同一句提示。 - 不变量与 fail-closed:非字符串
todo_id、非数组或含非字符串的required_write_scopes、以及不足 1024 字节的短范围均被跳过并保留内联;已进入交付(delivery_allowed !== false)或非normal_run/agent_workspace_repair的动作在函数入口即提前返回空数组。
- 职责与输入:在已验证
-
checkedContextPresentationPlan/contextPresentationPlan(loopx/control_plane/quota/turn_envelope.ts#L2003-L2012,#L2542-L2545)- 职责与调用路径:分别服务
complete_turn(校验签名捕获loopx_turn_envelope_v1并临时剥离schema_version与contract_binding以生成无修改原文的展示计划)与quota_packet路径,将progressivePreparationScopes(...)产出的作用域列表直接注入progressiveContextPlan(...)。 - 验证情况:TS 探针确认无论是直接
quota_packet还是经过composeCompleteTurnDecision签名的complete_turn载荷,均可正确生成对应unread_context_index.pointers并完整保留原contract_binding。
- 职责与调用路径:分别服务
-
progressiveContextPlan与requiredNativeContext(loopx/control_plane/quota/progressive_context.ts#L475-L556,#L560-L708)- 职责:消费
scopes,将每个scope.path写入deferred并在投影副本上删除对应叶子字段,同时将精确 JSON Pointer 写入context_details.unread_context_index.pointers,拼接所有read_instruction到context_details.instruction,并通过Buffer.byteLength(JSON.stringify(required)) - Buffer.byteLength(JSON.stringify(context)) + adjustment(remaining) - adjustment(tokens) < 0确保只有体积真正减小时才应用投影,同时保留 Python 大整数/浮点数字面量source_number_tokens血缘。
- 职责:消费
-
test_unbound_candidate_scopes_are_only_expanded_on_request(tests/control_plane/test_context_first_read.py#L316-L393)- 职责:以
workspace_repair(True/False) 参数化覆盖共享检出修复与独立 worktree 选单两条路径,通过真实loopx.entrypoint quota context-project --codex-app --context-delivery on子进程执行并读取first_read_command,断言短范围保留在suggested_actions[1]、长范围(355 项)从suggested_actions[0]与selected_todo移出首读并可通过context_details.command_template联合--select原样恢复,且原decision.json与缺席 registry/runtime 未受任何写入影响。
- 职责:以
规范依据与准则映射
本次依据修改前 origin/main(ff905437669054465a4d7aa8c70ba3396aaf9182)的既有公开契约文档 docs/reference/required-work-context.md 进行独立判定:
RWC-SEL-1(显式选单首读保留发现/选单命令与约束,docs/reference/required-work-context.md第 332-336 行):implemented — 由progressivePreparationScopes+initialContextReadGroups/prepareInitialOpening实现;经test_unbound_candidate_scopes_are_only_expanded_on_request与 File/SQLite 生产quota should-runCLI 探针验证。RWC-WR-2(工作树修复及准备阶段保留迁移/就绪义务,同 Turn 重跑 guard 恢复完整范围,不改变--context-delivery off视图,docs/reference/required-work-context.md第 349-355 行):implemented — 由progressivePreparationScopes与requiredNativeContext实现;经--context-delivery off对照、workspace_repair=True/False全流程迁移/绑定重入验证。RWC-DIGEST-3(延后详情必须从同份带摘要的原捕获经--select恢复且投影仅在字节缩小时生效,docs/reference/required-work-context.md第 153-156、239-244 行):implemented — 由requiredNativeContext字节保护及quota context-read --select验证。- 文档新增说明评估:PR 在
docs/reference/required-work-context.md#L211-L214新增 4 行说明未绑定 Todo 选择期间长候选写入范围按需展开语义,与修订前条文完全自洽,未放松任何既有限制。(注:文中第 349-355、384-388 行及第 401-410 行中文段未同步补充候选路径指针说明,因该文档非docs/architecture/rfcs/成对 RFC,不构成阻塞。)
对主干的风险 / Risks
负面案例、边界与反事实检查
- 默认关闭隔离(
default_off_isolation:isolated):在 CLI 探针中以--context-delivery off运行完全相同的共享检出修复与独立 worktree 选单夹具,并在 TS 对比探针中以progressive_enabled: false调用evaluateTurnEnvelope,输出均原样保留 355 条required_write_scopes在selected_todo与action_portfolio.suggested_actions[0]中且无context_details,与基线行为完全一致。 - Fail-closed 与非目标分支保持:经 TS 反事实探针验证,当候选
required_write_scopes小于 1024 字节、类型为非字符串数组(如[123])、或候选缺少字符串todo_id(如todo_id: 42)时,longScope/ 类型守卫均拒绝延后并保持原值内联;当处于claim_required(selection_required: false)或已就绪交付态(delivery_allowed: true)时,progressivePreparationScopes输出与origin/main完全一致。 - 权限边界(
authority_semantics:not_applicable):本改动仅调整已有渐进展示路径集合,不新增任何角色、生命周期或 schema 版本;首读阶段spend_allowed_now=false、delivery_allowed=false与selection_required=true全部保持不变,绑选并迁出后才由真实quota should-run准入提供完整当前范围,且准备与按需读取花费 0 quota。 - Caller / 作用域契合度(
scope_fit):改动直接命中quota should-run/quota context-project的生产调用链(quota_result_delivery.py/quota_capture.py->turn_envelope.py->turn_envelope.ts),非死代码或仅测试路径;不涉及跨领域硬编码文案、不引入字符串子串匹配替代类型守卫、未触发静默默认行为变更,且指令提示明确区分了条件按需读取与重跑 guard / 就绪后必读义务。
本地真实校验矩阵(exact head 5b28c05940,未等待或参考远程 CI)
npm run typecheck:control-plane:PASS。- TS 定向单测(
turn_envelope.test.ts,progressive_context.test.ts,context_delivery.test.ts,action_portfolio.test.ts,action_selection_admission.test.ts,interaction_contract.test.ts):PASS(167/167 passed)。 - Python 定向套件(
test_context_first_read.py,test_quota_authority_settlement_journey.py,test_quota_execution_preparation.py,test_workspace_git_fact_reads.py,test_saved_context_project.py,test_unadmitted_selection_construction.py,test_user_gate_lane_progress.py):466 passed, 14 skipped(经-rs确认全部 14 项跳过均为test_saved_context_project.py第 738/1225/1582 行因未设置LOOPX_NATIVE_CHECKPOINT_BIN的原生 Codex 二进制环境门控,与本 PR 无关);另单独跑通test_codex_context_lifecycle.py(171 passed)。 - 生产
quota should-runCLI 真实后端对比探针(File & SQLite × 共享检出工作树修复 & 独立 worktree 选单):PASS(File 修复态首读 1 页 9,964 B / 独立态 1 页 8,770 B;SQLite 修复态 1 页 9,968 B / 独立态 1 页 8,774 B;按需--select1 页恢复全部 355 项;绑定/迁出后同一 Turn 进入normal_run且完整范围就绪、quota 消耗为 0)。 - TS 基线对比与反事实探针(
ff90543766vs5b28c05940):PASS(证实旧 head 在独立 worktree 选单及修复选单下均未折叠候选范围,新 head 在quota_packet与complete_turn均正确延后并保留contract_binding)。 - 静态检查与门禁:
ruff check(loopx/control_plane/quota与改动测试):PASS;mypy(仓库配置 strict 集 17 文件):PASS;scripts/check_rfc_bilingual.py --base origin/main --head HEAD:PASS;git diff --check:PASS;loopx check --scan-path ...(3 个改动文件公开边界扫描):PASS。 loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main(临时挂载本地node_modules以运行 TS 词汇扫描,运行后已解除):PASS(gate.status = passed,direct_failure_count = 0,run_failure_count = 0,其中semantic-vocabulary-drift-smoke.py、quota-plan-smoke.py、公开边界扫描均通过;control-plane-maintainability-ratchet-smoke.py报告 1 项继承基线提醒oversized_decision_function位于未改动的loopx/control_plane/work_items/interaction_contract.py_admitted_interaction_next_cli_actions(58 决策点 / 96 语句 > 90),已在不变基线ff90543766上验证出现完全一致的失败签名,归类为pre_existing_unrelated,不阻塞本 PR)。
(非阻塞跟进建议:可按需在 tests/control_plane_ts/turn_envelope.test.ts 补一条纯 TS 单元测试直接覆盖 progressivePreparationScopes 的候选范围延后,并在后续文档整理中按需同步 docs/reference/required-work-context.md 对应中文段落。)
我的整体评价 / Verdict
综合上述架构、语义与本地实测证据,本次改动规模小而精准(code_volume: necessary;compatibility_assessment: retain;change_proportionality: proportionate,architecture_assessment: retain),只复用现有 TS PreparationScopeDetail 与 context_details 通道,在语义分类上属于局部演示规划改进(local_only,semantic_alignment: not_applicable),无新增词表、schema 版本或预算放宽。
从 outcome_impact 来看:long_horizon 为 improved——在跨多候选选择及跨工作树迁移的多步骤流程中,避免重复长范围列表挤爆首读分页并阻断备选可见性,同时保持相同 Turn 收据与准入边界;user_experience 为 improved——Agent/宿主首屏即可同时看到候选标识、短范围、选择命令与迁出/重跑指引而无需多轮分页翻找。针对渲染界面检查:已审阅 loopx/control_plane/quota/turn_envelope.ts、docs/reference/required-work-context.md 与 tests/control_plane/test_context_first_read.py,本 PR 仅涉及 CLI/JSON 渐进上下文展示,无任何渲染 UI 改动,visual_review 为 not_applicable,未验证界面范围 unverified_scope 为 none。相比 origin/main(ff90543766),精确 head 5b28c0594028ec213fcca4a4a09e83b36e15d3fd 消除了选单阶段重复长范围占页问题并保持禁用路径与非目标阶段完全等价。残余风险仅在于实测计量的是本地合成与孤立 File/SQLite 夹具的 reader 字节(未测真实 LLM 端 token 消耗),且该风险不影响控制面正确性与可恢复性。远端 PR 当前仍处于目标精确 head 5b28c0594028ec213fcca4a4a09e83b36e15d3fd(可无冲突合并至 origin/main)。
英文简短结论:
English Verdict: APPROVE — Exact head 5b28c0594028ec213fcca4a4a09e83b36e15d3fd safely defers long required_write_scopes on selected_todo and action_portfolio.suggested_actions during unbound Todo selection (both agent_workspace_repair and normal_run) in the TypeScript progressivePreparationScopes owner, preserves short scopes, selection commands, digest-bound --select recovery, and --context-delivery off parity, and passes TypeScript typecheck/167 TS tests, 466 targeted Python tests (14 native-bin-gated skips) + 171 lifecycle tests, File/SQLite production CLI probes, and quick premerge canaries (with one pre-existing unrelated ratchet advisory in untouched interaction_contract.py verified on ff90543766).
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · gpt-6.2-sol · OpenAI (runtime_reported, max)
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
动机 / Motivation
Codex App 使用原生首读选择工作,或为已选 Todo 取得受管 claim。主干的准备输出仍会内联很长的 Todo 写入范围。候选保留 Todo 身份、选择命令、claim 及停止条件,把达到阈值的范围列表放到原始 capture 的按需选择器。在 File 和 SQLite 复跑中,初次读取各减少 13,514 字节。单独读取原始范围及同一 Turn 的 ready 输出都得到完整 355 条。本次核验覆盖准备阶段的读取和授权边界。实际交付继续以 claim 后的当前 guard 为准。
改动思路 / Approach
继续用 TypeScript 的 Turn 投影计算可延迟字段,并交给原始 capture 的精确选择器读回。3 个文件只调整长范围的准备阶段投影、命令说明和本地验证。命令、选中项和短范围保持可直接读取。对准备阶段的匹配 Todo 或待选项,通过原始路径取回长列表。ready 输出保留完整范围。
具体改动 / Changes
精确 head fd7c76fd41c0c0126c7149ec4273f26516125ae1,diff base 6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25,3 个文件 +178/-8。逐项复核 same-todo-claim、unbound-candidate-detail、ready-and-spend。验收约定
关键代码讲解
- 只有宿主可执行、与已选 Todo 同 ID 的 claim_required 或现有显式选择进入相应准备投影。范围仍按原始 capture 路径读回。源码
- 未绑定选项保留已排序的候选身份和短列表。需要工作区修复与已有独立工作区两种情况下,长列表和已选范围都能按各自的指针读回。源码
- File 与 SQLite 用同一 Turn 走 claim 前后的真实 CLI。准备输出保留命令,ready 恢复完整范围和 settlement identity。源码
对主干的风险 / Risks
主要风险是把其他 Todo 的 claim 当成当前准备,或让已可交付的输出丢失范围。代码以选中 Todo 与 preparation 的身份相等作为门槛,保留当前授权字段和原始 capture 的读取路径。外来导航摘要与改动过的 capture 在直接复跑中被拒绝。
语义与 CI 对齐
聚焦套件在基线通过 266 项,候选通过 270 项。File 首读从 22,606 降到 9,092 字节,SQLite 从 22,620 降到 9,106 字节。两种 provider 的同轮 ready 都保留 355 条,准备和 claim 的配额支出为零。两版本复现同一可选参数 mypy 错误和 F401,来源为未变更的 Python 文件。
我的整体评价 / Verdict
批准当前提交。长范围延迟读取覆盖选项和 claim 两条准备路径,恢复同轮范围及授权边界通过验证。字节统计来自本地精确源代码的初次 JSON 读取。宿主部署和实际模型成本仍待验。
English verdict: APPROVE. The native preparation reads are smaller, with exact source recovery, complete same-Turn ready scopes, and unchanged spend and delivery gates.
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · Gemini · Google (self_reported)
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
动机 / Motivation
调度宿主与 Codex App 等原生控制面调用方在开启渐进上下文交付(--context-delivery on)执行 quota should-run 或 quota context-project 时会遇到该问题。 改动前,当处于未绑定 Todo 选单(含 agent_workspace_repair 工作区修复与独立工作区 normal_run)或已选定 Todo 但需先执行一次受管认领 claim_required 才能解锁交付时,长达 355 项的 required_write_scopes 会内联占满首读预算,在真实 File/SQLite CLI 上使 claim_required 首读超过 22 KB 并跨多页挤出候选与认领命令;改动后,首读仅保留候选与选中 Todo 身份、短范围、选单/认领命令及停止约束,将 >=1024 字节的长写入范围延后到带 SHA-256 摘要校验的原捕获按需 --select 指针中,使首读降至约 9 KB(单页),并在绑定/认领就绪后的同 Turn ready 决策恢复全部 355 项当前写入范围。 未绑定选单、工作区修复及同 ID claim_required 准备态下的首读保留关键控制信息并仅按需展开长 required_write_scopes,完成准备后同一 Turn 的 ready 决策内联交付完整当前范围且消耗 0 quota。 本 PR 不改变准入判定、候选排序规则与 --context-delivery off 完整输出,不放宽 ready 或其他阻断态,也未测量真实线上模型端 token 消耗。
改动思路 / Approach
本 PR 在 TypeScript 控制面 loopx/control_plane/quota/turn_envelope.ts 中扩展既有 progressivePreparationScopes(),统一服务于 quota_packet 与签名 complete_turn 展示规划,并在 Python 侧维持纯无状态读取恢复路径。复用 TypeScript 控制面 loopx/control_plane/quota/turn_envelope.ts 内唯一的 progressivePreparationScopes() 向 progressiveContextPlan() 与 requiredNativeContext() 传递延后路径,让 Python quota_capture.py / quota_context_reader.py 保持无状态 IO 适配器,不引入第二套展示规则或配置开关,同时受字节缩减检查与 todo_id/host_execution_allowed 守卫的 fail-closed 保护。 当前边界声明:仅针对未绑定选单(含工作区修复与独立选单)和同 todo_id claim_required 准备态下 >=1024 字节写入范围的按需折叠与回归测试,保持 ready 与 --context-delivery off 原样内联。
| 场景 / 状态 | 基线 origin/main (6a0f8bc17b) |
本 PR Head (fd7c76fd41) |
权威状态与恢复约束 |
|---|---|---|---|
agent_workspace_repair + 选单 |
仅延后 selected_todo.required_write_scopes;suggested_actions[*] 仍内联 |
同步延后 suggested_actions[*].required_write_scopes(>=1024B),尾注统一追加重跑 guard 指引 |
delivery_allowed=false、spend_allowed_now=false;迁出重跑后恢复 |
normal_run + 未绑定选单 |
候选与 selected_todo 长范围均内联 |
两者均按 >=1024B 延后并给出 JSON 指针,短范围(<1024B)保持内联 | selection_required=true 不变;按原捕获 --select 恢复 |
normal_run + claim_required |
selected_todo.required_write_scopes 内联(File 首读 22,577 B) |
同 todo_id 且允许宿主认领时延后 /selected_todo/required_write_scopes(File 首读降至 8,956 B) |
todo_id 不匹配或 host_execution_allowed!=true 时拒绝延后;todo claim 后同 Turn ready 交付全量 |
ready / --context-delivery off |
完整内联 | 与基线完全一致 | delivery_allowed=true 与默认关闭态零影响 |
具体改动 / Changes
精确 head fd7c76fd41c0c0126c7149ec4273f26516125ae1,对比合并基线 6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25,共修改 3 个文件(+178 / -8):生产控制面 1 个文件(loopx/control_plane/quota/turn_envelope.ts +18/-8)、公开参考文档 1 个文件(docs/reference/required-work-context.md +8/-0)、控制面集成测试 1 个文件(tests/control_plane/test_context_first_read.py +152/-0)。
关键代码讲解
progressivePreparationScopes:在入口确认interaction_contract版本为loopx_interaction_contract_v0、should_run === true、agent_channel.delivery_allowed === false且spend_allowed_now === false && spend_after_validation === false后,区分repair(agent_workspace_repair+agent_workspace_guard)、selecting(hasUnboundActionSelection(cli))与claiming(cli.selection_required !== true && normal_delivery_allowed === false && preparation.state === "claim_required" && preparation.delivery_allowed === false && typeof selected?.todo_id === "string" && preparation.todo_id === selected.todo_id && claim.host_execution_allowed === true)。仅当longScope(字符串数组且 UTF-8 JSON >= 1024B)满足时延后/selected_todo/required_write_scopes及selecting下的/action_portfolio/suggested_actions/<idx>/required_write_scopes,并在末条指针统一追加对应阶段的必读尾注。checkedContextPresentationPlan:同时覆盖普通quota_packet与签名complete_turn路径(剥离顶层schema_version与contract_binding后复用progressivePreparationScopes),由prepare_progressive_context/prepare_context_delivery调用并在requiredNativeContext确认总字节确实缩小时才生效。test_unbound_candidate_scopes_are_only_expanded_on_request与test_claim_preparation_keeps_requested_write_scopes_on_demand:分别以参数化workspace_repair(True/False)及真实 File/SQLite 后端hard_leasequota should-run验证短范围保留、长范围移出首读并经command_template --select原样恢复,以及todo claim后同一 Turnready交付完整 355 条范围且settlement_identity一致、0 quota 消耗。
规范依据与准则映射
依据修改前 origin/main 修订 6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25 的公开契约文档 https://github.com/loopx-project/loopx/blob/6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25/docs/reference/required-work-context.md 逐项映射(PR 在该文档第 211-218 行补充的说明与既有条款完全一致,未放宽任何既有限制):
RWC-SEL-OPEN(显式选单首读保留候选标识、发现与选单命令及停止约束,第 335-339 行):implemented — 由progressivePreparationScopes与initialContextReadGroups实现,经test_unbound_candidate_scopes_are_only_expanded_on_request验证。RWC-WR-CLAIM(工作区修复与受管认领准备保留迁移/认领指引并在同 Turnready恢复完整范围,第 352-358 行):implemented — 由progressivePreparationScopes实现,经test_claim_preparation_keeps_requested_write_scopes_on_demand与基线/Head File/SQLite 实测对比验证。RWC-OFF-PARITY(--context-delivery off、ready、短列表及异常/不匹配准备态保持原始全量内联):implemented — 由requiredNativeContext与progressivePreparationScopes类型/身份守卫保证,经 TS+Python 反事实探针验证。
对主干的风险 / Risks
- 默认关闭与边界隔离(
default_off_isolation:isolated):progressive_enabled: false/--context-delivery off入口直接跳过延后,保留全部 355 条范围与无context_details输出;在claiming路径中若preparation.todo_id !== selected.todo_id、host_execution_allowed !== true、required_write_scopes小于 1024 字节或非字符串数组,或已进入delivery_allowed: true的ready状态,反事实探针均证实保持原值内联且不修改contract_binding。 - 生产调用链与权限边界(
scope_fit/authority_semantics):改动直接命中quota should-run与quota context-project生产入口(quota_capture.py->turn_envelope.py->turn_envelope.ts),无死代码;未新增任何 actor 生命周期、schema 版本或权限声明,spend_allowed_now=false、delivery_allowed=false与零 quota 准备语义不变。非阻塞细节提示:docs/reference/required-work-context.md对应中文段落可按需在后续文档整理中同步补充claim_required指针说明(该文档非成对 RFC,不构成阻塞)。
语义与 CI 对齐
本 PR 属于局部展示规划改进(local_only,未改动共享词表或持久化 schema,semantic_alignment: not_applicable)。本地直接校验结果(未等待或参考远程 CI,wait_for_ci: false):
npm run typecheck:control-plane与 6 份定向 TS 单测(turn_envelope.test.ts,progressive_context.test.ts,context_delivery.test.ts,action_portfolio.test.ts,action_selection_admission.test.ts,interaction_contract.test.ts):PASS(167/167 passed)。- Python 定向套件:
test_context_first_read.py168 passed;test_codex_context_lifecycle.py+test_quota_execution_preparation.py+test_quota_authority_settlement_journey.py305 passed;test_quota_settlement_cli.py -k "claim or selection or scope"38 passed(注:早先将test_quota_settlement_cli.py与跨文件混合并发运行时出现 pytest sessioneffect-runtime0临时目录清理碰撞报错,已对碰撞用例test_recovery_does_not_bind_current_replan_and_reenters_same_turn单独复跑 2/2 PASS 排除回归)。 - 基线 vs Head 真实 File/SQLite CLI 对比(
claim_required355 项范围):File 首读从基线6a0f8bc17b的 22,577 B 降至 Headfd7c76fd41的 8,956 B(序列化页 10,138 B),SQLite 从 22,591 B 降至 8,970 B(序列化页 10,152 B),两后端均降至单页且--select与todo claim后ready均恢复完整 355 条。 - TS+Python 反事实探针(覆盖
mismatch_todo、host_allowed=False、progressive_enabled=False、短范围、ready及签名complete_turn):PASS。 ruff check tests/control_plane/test_context_first_read.py、git diff --check、scripts/check_rfc_bilingual.py、loopx check --scan-path(3 个改动文件公开边界扫描):PASS。loopx canary premerge --tier quick --from-git-diff --git-diff-base 6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25:PASS(gate.status = passed,merge_gate_passed = true,direct_failure_count = 0,run_failure_count = 0)。mypy(仓库配置 strict 17 文件):报 1 项既有的interaction_contract.py:1004类型错误,已在合并基线6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25上复现相同错误签名(pre_existing_unrelated)。
我的整体评价 / Verdict
从 outcome_impact 评估:long_horizon 为 improved(消除选单与普通受管认领前重复长写入范围对首读分页预算的挤压,同时在同 Turn 认领或迁出就绪后恢复完整范围与原 settlement_identity),user_experience 为 improved(首屏即可完整呈现候选、认领与迁移命令而无须多轮翻页)。本 PR 仅涉及控制面 JSON 渐进展示规划,无任何渲染 UI 改动,visual_review 为 not_applicable(已审阅全部 3 个改动文件,未验证界面范围 unverified_scope 为 none)。综合 code_volume(necessary、compatibility_assessment: retain)、change_proportionality(proportionate、architecture_assessment: retain)、default_off_isolation(isolated)、authority_semantics(not_applicable)及局部词表评估(local_only),整体实现简洁精准。残余风险为未测量真实线上模型端 token 消耗且未重跑完整全仓 Python 矩阵,但不影响控制面正确性。当前远程 PR 仍位于目标精确 head fd7c76fd41c0c0126c7149ec4273f26516125ae1。
英文简短结论:
English verdict: APPROVE — Exact head fd7c76fd41c0c0126c7149ec4273f26516125ae1 cleanly defers long (>=1024 B) required_write_scopes on selected_todo and action_portfolio.suggested_actions during unbound Todo selection, workspace repair, and matching claim_required preparation in TypeScript progressivePreparationScopes, cuts claim_required first-read size from ~22.6 KB to ~9.0 KB on real File and SQLite backends while preserving exact --select recovery, same-Turn ready scope restoration, complete_turn signing, and --context-delivery off parity, and passes TS typecheck + 167 TS tests, 473 + 38 targeted Python tests, counterfactual probes, Ruff/boundary/RFC checks, and quick premerge canaries (with pre-existing mypy error in untouched interaction_contract.py verified on base 6a0f8bc17b).
Goal And Delivered Outcome
Large write-scope lists can fill the initial quota read while an Agent is choosing a Todo, relocating to a worktree, or preparing an ordinary managed claim. The initial read keeps the candidate or selected Todo, the available action and the current stops. Long lists are available at their original digest-bound addresses. The guard after binding and claim supplies the complete current scope before delivery.
main.model_agent(OpenAI Codex, GPT-6).docs/reference/required-work-context.md. The claim presentation matches the selected Todo with the current claim before deferring its scope.Validation
fd7c76fd41c0c0126c7149ec4273f26516125ae1against6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25.finished. Inputs are synthetic File and SQLite fixtures.regression_paritypassedreal_entrypointpassedintegrationpassedunitpassedstaticpassedstaticfailedunitnot_runThe measurements cover the production CLI on isolated fixtures. Live host and model costs remain unmeasured. Required Python checks and exact-head independent review remain open.